Recollida Requisits
Contextualització de l’organització client
L’organització que ha sol·licitat aquest projecte és Aprop Garraf, una entitat compromesa amb la mobilitat sostenible i el foment de l’ús de la bicicleta com a mitjà de transport ecològic i accessible. L’organització busca incentivar l’ús responsable de les bicicletes mitjançant la creació d’una aplicació que permeti registrar rutes i recompensar els ciclistes per la distància recorreguda.
Objectius de l’organització
Aprop Garraf té com a finalitat principal promoure la mobilitat sostenible i incentivar el transport actiu dins la comunitat. Els objectius específics de l’entitat són:
-
Fomentar l’ús de la bicicleta per reduir la dependència dels vehicles motoritzats.
-
Premiar els usuaris actius a través d’un sistema de punts bescanviables per productes o serveis locals.
-
Crear una comunitat de ciclistes que participin activament en la iniciativa.
-
Recolzar el comerç local, promovent la col·laboració amb establiments que ofereixin recompenses als ciclistes.
-
Garantir un registre fiable de rutes, que permeti validar l’activitat dels usuaris de manera transparent i segura.
A través d’aquesta aplicació, Aprop Garraf busca combinar la tecnologia amb la sostenibilitat, creant un entorn en què la mobilitat neta sigui atractiva i accessible per a tothom.
Breu resum del projecte
Aquest projecte té com a objectiu el desenvolupament d’un sistema digital compost per una aplicació mòbil per als usuaris ciclistes i una plataforma web per a l’administrador. La iniciativa és impulsada per Aprop Garraf amb l’objectiu de fomentar la mobilitat sostenible mitjançant un sistema de recompenses per als ciclistes.
Estructura del sistema
-
Aplicació mòbil per a Android: Utilitzada pels ciclistes per registrar les seves rutes, acumular punts en funció dels quilòmetres recorreguts i bescanviar-los per recompenses en establiments col·laboradors.
-
Plataforma web per a l’administrador: Serveix per gestionar els usuaris, validar les rutes i controlar el sistema de punts i recompenses.
Funcionalitats principals
-
Registre i validació d’usuaris: L’usuari s’haurà de registrar a l’aplicació i l’administrador validarà manualment cada compte des de la plataforma web.
-
Seguiment de rutes mitjançant geolocalització: L’app mòbil registrarà els trajectes dels ciclistes en temps real.
-
Càlcul i acumulació de punts: Els punts s’assignaran segons la distància recorreguda i es podran bescanviar per recompenses.
-
Sistema de recompenses en establiments locals: Els usuaris podran utilitzar els punts acumulats per obtenir productes o serveis en comerços col·laboradors.
-
Gestió centralitzada des de la plataforma web: L’administrador podrà validar rutes, aprovar registres d’usuaris i gestionar el catàleg de recompenses.
Els requeriments funcionals i no funcionals
Requeriments funcionals (RF)
Els requeriments funcionals indiquen les accions que ha de permetre fer l’aplicació per als diferents usuaris (ciclista i administrador).
-
RF01: Validar ruta → L’administrador revisa una ruta i la valida si compleix els criteris establerts. La ruta es troba prèviament no validada i quan es valida la ruta s’afegeix el saldo al compte de l’usuari.
-
RF02: Invalidar ruta → Si una ruta no compleix els requisits, l’administrador pot invalidar-la.
-
RF03: Iniciar ruta → L’usuari pot començar una nova ruta manualment des de l’aplicació mòbil, sempre que no tingui cap altra ruta en curs.
-
S’haurà de consultar el paràmetre de sistema Temps màxim d’aturada per si s’ha de considerar que s’ha de finalitzar la ruta de manera automàtica.
-
-
RF04: Visualitzar detalls ampliats d’una ruta → El sistema ha de permetre a l’usuari ciclista consultar la informació detallada de les rutes que ha realitzat. Aquesta informació ha de ser mostrada de manera clara i precisa, incloent:
-
Distància recorreguda: Mostrada amb precisió de metres, des del punt inicial fins al punt final de la ruta.
-
Temps total de la ruta: El temps complet des que la ruta va començar fins que es va finalitzar.
-
Velocitat màxima: La velocitat més alta registrada durant la ruta.
-
Velocitat mitjana: Calculada com la distància recorreguda dividida pel temps total.
-
Mapa interactiu: Visualització de tots els punts recorreguts sobre un mapa, connectats per línies.
-
El mapa ha de permetre funcionalitats de zoom i desplaçament lateral per una millor visualització.
-
En fer clic sobre qualsevol punt del recorregut, es mostrarà la seva informació de latitud i longitud.
-
-
Aquesta funcionalitat serà accessible només per a l’usuari ciclista per les seves pròpies rutes. L’administrador, en canvi, tindrà accés per visualitzar qualsevol ruta independentment de l’usuari que l’hagi realitzat.
-
-
RF05: Finalitzar ruta → Un cop acabada la ruta, l’usuari pot finalitzar-la manualment perquè sigui processada.
-
Només es podrà finalitzar la ruta que es trobi en estat "en curs".
-
Un cop finalitzada, ja no es podran afegir més punts a la ruta.
-
Un cop finalitzada, la ruta quedarà per defecte en estat "no validada" i haurà d’esperar l’aprovació de l’administrador per passar a "validada".
-
Un cop finalitzada, l’usuari visualitzarà els detalls de la ruta, seguint la funcionalitat descrita en RF Visualitzar detalls d’una ruta o Visualitzar detalls ampliats d’una ruta.
-
-
RF06: Llistar rutes → L’usuari pot veure un llistat de les seves rutes anteriors amb informació bàsica.
-
La velocitat mitjana es calcula com la distància recorreguda dividida pel temps total.
-
-
RF09: Crear recompensa → El sistema ha de permetre crear una nova recompensa i assignar-la a un punt de bescanvi.
-
El punt de bescanvi serà un string amb el nom del negoci i l’adreça.
-
-
RF11: Eliminar recompensa disponible → L’administrador pot suprimir recompenses que no estiguin reservades o assignades.
-
RF12: Reservar recompensa → L’usuari pot reservar una recompensa si té suficients punts disponibles.
-
Saldo suficient: El valor unitari de la recompensa no pot superar el saldo disponible de l’usuari en el moment de la reserva.
-
Reserva única: Un usuari només pot tenir una recompensa reservada al mateix temps. Fins que aquesta no sigui recollida o desassignada, no podrà reservar-ne cap altra.
-
Disponibilitat de la recompensa: No es podrà fer una reserva si la recompensa ja està assignada, reservada o recollida per un altre usuari.
-
-
RF14: Assignar recompensa → Un cop l’usuari ha reservat una recompensa, l’administrador ha d’assignar-la abans que pugui ser recollida.
-
RF16: Recollir recompensa → Un cop reservada, l’usuari ha d’anar a la botiga i mostrar la seva reserva per obtenir la recompensa.
-
Consultar la recompensa assignada: L’usuari podrà veure la recompensa que té assignada, incloent el nom del punt de bescanvi i la descripció de la recompensa.
-
Mostrar la informació de la recompensa al punt de bescanvi: Quan l’usuari arribi al punt de recollida, podrà visualitzar en el seu dispositiu el nom del punt de bescanvi i el nom de la recompensa de manera destacada i clara.
-
Confirmació de la recollida: Un cop el ciclista hagi rebut la recompensa, haurà de fer clic en un botó anomenat "Entregat". En fer-ho, apareixerà una imatge gran en el dispositiu del ciclista amb la paraula "ENTREGAT" de manera visible i clara.
-
Marcar la recompensa com a recollida: Després de la confirmació, la recompensa es marcarà com a "recollida" al sistema. Es guardarà la data i hora de la recollida, i es bloquejaran qualsevol altre tipus de modificació sobre aquesta recompensa.
-
-
RF18: Llistar recompenses → El sistema ha de permetre llistar les recompenses mostrant les següents dades per cada recompensa:
-
Nom de la recompensa
-
Punt de bescanvi
-
Punts associats a la recompensa
-
Estat de la recompensa (disponible, reservada, assignada, recollida)
-
Nom de l’usuari (només en el cas que estigui reservada, assignada o recollida)
-
Condicions d’accés:
Ciclista: Només pot veure les recompenses disponibles o les seves pròpies recompenses (reservades, assignades o recollides).
Administrador: Pot veure el llistat complet de totes les recompenses, independentment de l’estat de cada una.
-
RF21: Mostrar detall de la recompensa → El sistema ha de permetre consultar les característiques d’una recompensa seleccionada dins el llistat de recompenses (segons RF18), mostrant els següents detalls:
-
Nom de la recompensa
-
Nom complet de l’usuari (només en el cas que sigui una recompensa reservada, assignada o recollida per un ciclista)
-
Nom del punt de bescanvi
-
Adreça del punt de bescanvi
-
Estat de la recompensa (disponible, reservada, assignada o recollida)
-
-
RF22: Crear usuari → L’administrador pot donar d’alta nous usuaris després de la seva validació manual.
-
RF23: Modificar usuari → L’administrador pot modificar les dades d’un usuari existent.
-
Els usuaris ciclistes que no són administradors tan sols poden modificar el seu perfil.
-
-
RF25: Llistar usuaris → Es pot veure una llista d’usuaris registrats al sistema amb la següent informació:
-
Nom complet de l’usuari
-
Correu electrònic de l’usuari
-
Estat de l’usuari (actiu o desactivat)
-
Rol de l’usuari (ciclista, admin)
-
-
RF26: Visualitzar detalls de l’usuari → L’administrador pot accedir a la informació completa d’un usuari concret:
-
Foto de l’usuari (si en té)
-
Nom complet
-
Correu electrònic
-
Estat actual (actiu o desactivat)
-
Rol (ciclista, admin)
-
Saldo disponible (validat)
-
Historial de rutes: Una llista amb totes les rutes que l’usuari ha realitzat, amb el seu estat actual (no validada, validada) i els punts de saldo associats.
-
Historial de recompenses: Detalls de les recompenses que l’usuari ha reservat, assignat, recollit amb l’estat de cadascuna.
-
En el cas de l’usuari ciclista, només podrà visualitzar les dades del seu perfil.
-
-
RF27: Recuperar password usuari → El sistema ha de permetre que qualsevol usuari, tant administrador com ciclista, pugui recuperar el password en cas d’haver-lo oblidat d’una manera segura.
-
RF29: Login / Logout → Els usuaris han de poder iniciar i tancar sessió de manera segura.
-
Usuari Ciclista:
-
Login: El ciclista ha de poder fer login a l’app mòbil utilitzant el seu correu electrònic i contrasenya.
-
Logout: El ciclista ha de poder sortir de la seva sessió de l’app mòbil en qualsevol moment.
-
-
Usuari Administrador:
-
Login: L’administrador ha de poder fer login tant a l’app mòbil com al frontend web utilitzant el seu correu electrònic i contrasenya.
-
Logout: L’administrador també ha de poder sortir de la seva sessió tant a l’app mòbil com al frontend web en qualsevol moment.
-
-
-
RF36: Modificar paràmetres del sistema → L’administrador pot modificar aspectes generals del sistema:
-
Velocitat màxima vàlida: Determina la velocitat màxima permesa per registrar una ruta correctament. Per defecte, 60 km/h.
-
Temps màxim d’aturada: Temps màxim que un usuari pot estar aturat abans que la ruta es finalitzi automàticament. Per defecte, 5 minuts.
-
Conversió entre saldo i quilòmetres: Defineix la relació entre la distància recorreguda i els punts acumulats. Per defecte, 1 km = 1 punt.
-
Temps màxim per recollir la recompensa: Període màxim per recollir una recompensa assignada al punt de bescanvi. Per defecte, 72 hores.
-
Requeriments no funcionals (RNF)
Requeriments generals
-
RN01: L’aplicació ha de permetre fins a 50 usuaris actius.
-
RN02: L’arquitectura ha de ser client-servidor, amb API REST en Spring Boot.
-
RN03: El sistema ha de tenir un registre de logs per detectar errors i incidències.
-
RN04: El codi ha de ser eficient i sense redundàncies, seguint bones pràctiques de desenvolupament.
-
RN05: L’estructura del codi ha de seguir patrons d’arquitectura adequats per a cada tecnologia utilitzada.
-
RN06: Les classes i mètodes han d’estar documentats amb JavaDoc per al backend i KDoc per al codi Kotlin.
-
RN07: Qualsevol excepció que es produeix durant l’execució ha de ser degudament informada a l’usuari amb informació concreta i comprensible.
-
RN09: S’ha d’utilitzar git/gitlab per implementar el projecte de forma òptima.
-
RN12: La comunicació entre el frontend mòbil i el backend s’ha de portar a terme mitjançant els principis REST.
Requeriments del frontend mòbil (aplicació)
-
RN20: L’app s’ha de desenvolupar amb Android Studio i el llenguatge Kotlin.
-
RN21: Ha de seguir l’arquitectura Feature Layer i Clean Architecture.
-
RN22: Ha de seguir el patró MVVM per separar la lògica de negoci i la interfície d’usuari.
-
RN23: La interfície gràfica s’ha d’implementar amb Jetpack Compose.
-
RN24: Ha de seguir les directrius de Material Design.
Requeriments del backend
-
RN41: L’estructura del projecte ha de ser de tipus Maven.
-
RN42: Les capes de servei, lògica de negoci i de persistència han d’estar ubicades al backend.
-
RN43: El backend s’ha d’implementar mitjançant Spring Boot.
Requeriments del frontend web
-
RN51: L’usuari administrador ha de poder accedir a l’aplicació mitjançant un navegador web.
-
RN52: Ha de ser responsive i accessible.
-
RN53: La interfície ha de ser intuïtiva i eficient.
Guions per actors
Actor: Ciclista (Usuari de l’App Mòbil)
-
RF03: Iniciar ruta → L’usuari pot començar una nova ruta manualment des de l’aplicació mòbil, sempre que no tingui cap altra ruta en curs.
-
RF04: Visualitzar detalls ampliats d’una ruta → L’usuari pot consultar la informació detallada de les seves rutes, incloent distància, temps, velocitat i visualització en mapa interactiu.
-
RF05: Finalitzar ruta → L’usuari pot finalitzar la seva ruta manualment perquè sigui processada.
-
RF06: Llistar rutes → L’usuari pot veure un llistat de les seves rutes anteriors amb informació bàsica.
-
RF12: Reservar recompensa → L’usuari pot reservar una recompensa si té suficients punts disponibles.
-
RF16: Recollir recompensa → L’usuari ha d’anar a la botiga i mostrar la seva reserva per obtenir la recompensa.
-
RF18: Llistar recompenses → Els usuaris podran veure un llistat de totes les recompenses disponibles i el seu estat.
-
RF21: Mostrar detall de la recompensa → Mostra les característiques d’una recompensa seleccionada dins el llistat de recompenses.
-
RF23: Modificar usuari → L’usuari tan sols podrà modificar les seves dades d’usuari.
-
RF26: Visualitzar detalls de l’usuari → L’usuari podrà veure les seves dades d’usuari, és a dir, el seu perfil.
-
RF27: Recuperar password usuari → L’usuari pot sol·licitar la recuperació de la seva contrasenya en cas d’oblit.
-
RF29: Login / Logout → L’usuari pot iniciar sessió i tancar-la a l’aplicació mòbil.
Actor: Administrador (Usuari de la Plataforma Web)
-
RF01: Validar ruta → L’administrador revisa una ruta i la valida si compleix els criteris establerts, afegint els punts corresponents a l’usuari.
-
RF02: Invalidar ruta → Si una ruta no compleix els requisits, l’administrador pot invalidar-la.
-
RF03: Iniciar ruta → L’usuari pot començar una nova ruta manualment des de l’aplicació mòbil, sempre que no tingui cap altra ruta en curs.
-
RF04: Visualitzar detalls ampliats d’una ruta → L’usuari pot consultar la informació detallada de les seves rutes, incloent distància, temps, velocitat i visualització en mapa interactiu.
-
RF05: Finalitzar ruta → L’usuari pot finalitzar la seva ruta manualment perquè sigui processada.
-
RF06: Llistar rutes → L’usuari pot veure un llistat de les seves rutes anteriors amb informació bàsica.
-
RF09: Crear recompensa → L’administrador pot crear una nova recompensa i assignar-la a un punt de bescanvi.
-
RF11: Eliminar recompensa disponible → L’administrador pot suprimir recompenses que no estiguin reservades o assignades.
-
RF12: Reservar recompensa → L’usuari pot reservar una recompensa si té suficients punts disponibles.
-
RF14: Assignar recompensa → Un cop l’usuari ha reservat una recompensa, l’administrador ha d’assignar-la abans que pugui ser recollida.
-
RF16: Recollir recompensa → L’usuari ha d’anar a la botiga i mostrar la seva reserva per obtenir la recompensa.
-
RF18: Llistar recompenses → L’administrador pot veure un llistat de totes les recompenses disponibles i el seu estat.
-
RF21: Mostrar detall de la recompensa → L’administrador pot consultar les característiques d’una recompensa seleccionada.
-
RF22: Crear usuari → L’administrador pot donar d’alta nous usuaris després d’una validació manual.
-
RF23: Modificar usuari → L’administrador pot modificar les dades d’un usuari existent.
-
RF25: Llistar usuaris → L’administrador pot veure una llista d’usuaris registrats.
-
RF26: Visualitzar detalls de l’usuari → L’administrador pot accedir a la informació completa d’un usuari.
-
RF27: Recuperar password usuari → L’administrador pot generar un procés segur de recuperació de contrasenya per als usuaris.
-
RF29: Login / Logout → L’administrador pot iniciar sessió tant a l’aplicació mòbil com a la plataforma web.
-
RF36: Modificar paràmetres del sistema → L’administrador pot modificar aspectes generals com la velocitat màxima permesa o el temps màxim d’aturada.